MIRC DIALOGS  by pai03/22/99

      This article attempts to teach all the important, basic stuff about mIRC 
      dialogs. However, you MUST be reasonably proficient at scripting, as this 
      tutorial will be very fast-paced and condensed, to cover a lot of 
      material. 
      For those who do not know, dialogs are those neat informative boxes in 
      Windows that pop up to let you enter or change options. mIRC's options 
      dialogs are examples. As of mIRC 5.5, features have been added to let a 
      script create and use these dialogs. (sometimes referred to as GUI.) 
      The following file does NOT contain the same samples used in this article, 
      although some are similar. They are useful as examples for you to work 
      from and learn more about dialogs. 
            Download dialog-samples.mrc (Dialog examples )


            A MINIMAL DIALOG 


      Dialogs are created using dialog tables. A dialog table defines all the 
      parts of the dialog, and is stored in a remote script file. Here is a very 
      basic dialog table. 
      ; This is a simple dialog example- the bare minimum. 

      dialog bare { 
        title "Test" 
        size -1 -1 -1 -1 
        button "Done", 100, 20 20 40 40, OK 
      } 

      By itself, this code does nothing. You must tell mIRC to open a dialog 
      using the /dialog command or $dialog identifier. $dialog opens 'modal' 
      dialogs- these dialogs require you to respond before you can return to 
      mIRC. /dialog opens 'nonmodal' dialogs- like normal windows, you can 
      switch back and forth without closing the dialog. 
      When you open a dialog, you need to name TWO things- the dialog table, and 
      a name for the dialog. These are often the same, but do not need to be the 
      same. Only one dialog with a given name can open at once; many dialogs can 
      share the same table however. The table tells mIRC what to put in the 
      dialog; from that point on, the dialog is referred to by it's name. Think 
      of the table as a 'template' to build the dialog from. 
      To open the above dialog, use the following- 
      /dialog -m bare bare 

      The first 'bare' is the dialog name. The second 'bare' is the dialog 
      table. '-m' means to open a modeless (nonmodal) dialog. (this is required 
      when opening a new dialog with /dialog.) 
      This will open a basic dialog with nothing more than a button to close it. 
      Let's examine the dialog table in detail. (make sure you understand the 
      details, as later elements build on these concepts) 
      dialog bare { 

      The dialog prefix names the table, and the opening brace is required to 
      start the table. 
      title "test" 

      This line simply names the dialog. It is not required, but usually used. 
      size -1 -1 -1 -1 

      This line positions and sizes the dialog. Negative ones are to use default 
      sizes. The first two numbers are X and Y position onscreen- Negative ones 
      mean to center the dialog, and are commonly used. The second pair of 
      numbers represent the width and height of dialog in pixels. These are 
      usually given, but you can specify negative ones for 'default' sizing. 
      (not recommended) 
      button "Done", 100, 20 20 40 40, OK 

      All remaining lines create controls in the dialog. This creates a push 
      button- hence the word 'button'. The "Done" is the label for the button, 
      always enclosed in quotes. The next number is the control's ID. An ID is a 
      number from 1 to 250 that represents the control. All controls must have 
      unique IDs, they are used to refer to the controls within events, etc. The 
      next four numbers represent the X position, Y position, width, and height 
      of the button. All numbers are in pixels. This will create a button 40 
      wide, 40 high, at 20 pixels across and 20 pixels down. Finally, special 
      'styles' are listed. In this case we give the 'OK' style, which makes this 
      button close and accept the dialog. Styles are OPTIONAL, and more than one 
      can be given. 
      } 

      The closing brace ends the dialog. 
      This is the bare minimum dialog- ALL dialogs MUST have at least one button 
      with the 'OK' or 'Cancel' style. 
      It is important that you understand how to position and size this button, 
      understand it's ID number, and styles, as all controls use this format. 

            A SIMPLE AWAY DIALOG 


      Here we will look at a slightly more complex dialog, with an editbox, 
      text, and some checkboxes. 
      dialog awayd { 
        title "Set Away" 
        size -1 -1 300 120 
        
        text "Away message?", 202, 14 10 80 20 
        
        edit "", 1, 10 30 280 22, result autohs 
        
        check "&Pager on", 2, 10 60 65 16 
        check "&Logging on", 3, 95 60 75 16 
        
        button "OK", 101, 10 86 80 25, OK default 
        button "Cancel", 102, 110 86 80 25, cancel 
      } 

      Don't get too worried- Most of this is pretty simple stuff to understand 
      if you got the last example. The title is the same, and the size specifies 
      the width and height of the dialog. 
      The next line specifies a text control. This is simply plain, static text. 
      '202' is the id of the control (remember, all controls have an ID) and 
      then you have the position, width, and height of the control. (if you 
      don't make the control big enough, the text will wrap or clip.) 
      The next line defines an editbox. This is editable text. Similar to the 
      static text, except there is no text given ("" means empty, so the editbox 
      starts empty) and the two new styles. The 'result' style means that this 
      editbox will be returned from a $dialog. (we'll discuss this later.) The 
      'autohs' style means that the editbox scrolls horizontally as needed. 
      (automatic horizontal scroll) Without this style, you can only enter as 
      much text as will fit. 
      The next two lines define checkboxes. They are defined exactly like text. 
      They will appear as a standard checkbox, with on and off states. All 
      checkboxes default to off. 
      The final two lines define two buttons. This is the same as the button 
      from the last example, except for the styles. 'OK' marks the accept 
      button, 'cancel' marks the cancel button, and 'default' marks the default 
      button- the one that is pressed if you simply press Enter. (in most 
      cases.) 
      To run this dialog, use this alias- 
      alias dlg2 { echo -s You entered $dialog(awayd,awayd,-4) } 

      This will pop up the dialog, and if you press OK, display the reason you 
      entered. $dialog is used to pop up this dialog. The first parameter is the 
      dialog name, the second is the dialog table, and the third tells mIRC the 
      'parent' for the dialog. This isn't really that important usually- 
      Negative four makes the active dialog/window the parent, and is usually 
      the best choice. 
      The $dialog identifier, unlike /dialog, STOPS all script processing until 
      the dialog completes. It then returns whatever was entered in the 'result' 
      control- the editbox with the 'result' style in this case. 
      The end result- $dialog pops up the dialog, you enter an away reason, 
      click OK, and then $dialog returns to the alias and returns the away 
      reason you entered. 

            WORKING WITH CHECKBOXES 


      The above dialog has two nice checkboxes that don't do a damn thing. Let's 
      learn some dialog events and how to interface to these checkboxes. 
      All dialog events are of the following form- 
      on *:DIALOG:name:event:id:{ } 

      'name' is the dialog name, (not table) event is an event type, (such as 
      'sclick' for a click) and 'id' is the ID of the control, or * for any 
      control. Make sure you still have the away system dialog loaded from the 
      last example, and add the following code- 
      on *:DIALOG:awayd:sclick:2:{ 
        set %checkpager $did(2).state 
        if ($did(2).state) echo -s Pager on 
        else echo -s Pager off 
      } 
      on *:DIALOG:awayd:sclick:3:{ 
        set %checklog $did(3).state 
        if ($did(3).state) echo -s Log on 
        else echo -s Log off 
      } 

      These events 'detect' clicking on the checkboxes, and display appropriate 
      messages. 
      Notice the format of the event, first- 'awayd' is the dialog name, 
      'sclick' is the event type, and '2' and '3' are the IDs of the checkboxes. 

      The first line then stores the state of the checkbox into a variable. 
      $did() is used to retrieve info on dialog controls. $did(2) retrieves info 
      on dialog control 2. $did(2).state gets the state of the checkbox that is 
      control 2. It will return 0 for unchecked (off) and 1 for checked. (on) So 
      this stores a 0 or 1 in the variable, depending on whether the checkbox is 
      selected. 
      The code then checks $did().state again. If it is selected (1) an 'on' 
      message is displayed, otherwise an 'off' message is displayed. 
      This works great so far, except the state of the checkboxes isn't restored 
      when you open the dialog. Try this event for that- 
      on *:DIALOG:awayd:init:*:{ 
        if (%checkpager) { did -c awayd 2 } 
        if (%checklog) { did -c awayd 3 } 
      } 

      This event, the 'init' event, is called when the dialog opens. The ID 
      given is '*'- when the init event is called, the ID is 0, but * works as 
      well, for 'any id'. 
      Each line checks one of the variables, and if set, checks the specified 
      checkbox in the dialog. This is done with the /did command- used to 
      manipulate dialog controls. '-c' is used to select (check) a control. 
      'awayd' is the dialog name. '2' and '3' are the IDs for the checkbox 
      controls. 
      Once this section and the previous sections are entered, the away dialog 
      will remember it's settings each time it opens, unless the variables are 
      cleared. 

            RADIO BUTTONS 


      Radio buttons are similar to checkboxes, except you can only have one 
      radio button out of a group selected at one time. Try this dialog- 
      dialog grouping { 
        title "Radio Buttons" 
        size -1 -1 300 200 
        
        radio "Option A", 1, 5 5 120 16, group 
        radio "Option B", 2, 5 25 120 16 
        
        radio "Selection A", 3, 150 5 120 16, group 
        radio "Selection B", 4, 150 25 120 16 
        radio "Selection C", 5, 150 45 120 16 
        
        button "OK", 100, 120 120 60 25, ok 
      } 

      on *:DIALOG:grouping:init:*:{ 
        %@opt = A 
        %@sel = A 
        did -c $dname 1 
        did -c $dname 3 
      } 

      on *:DIALOG:grouping:sclick:1:{ %@opt = A } 
      on *:DIALOG:grouping:sclick:2:{ %@opt = B } 

      on *:DIALOG:grouping:sclick:3:{ %@sel = A } 
      on *:DIALOG:grouping:sclick:4:{ %@sel = B } 
      on *:DIALOG:grouping:sclick:5:{ %@sel = C } 

      on *:DIALOG:grouping:sclick:100:{ 
        echo -s Option %@opt and Selection %@sel 
        unset %@opt %@sel 
      } 

      alias dlg4 { dialog -m grouping grouping } 

      This is a large chunk of dialog code, but it shouldn't be too hard to 
      understand. The dialog table is similar to what you've already seen. The 
      only change is 'radio' controls. They are EXACTLY like checkbox controls, 
      except they appear as round dots instead of squares with 'X'. Also, only 
      ONE radio can be selected at a time, within a group. 
      This is what the 'group' style signifies- The start of a group. As you can 
      see here, we have two groups of radio buttons. 
      The 'init' event presets some variables, and preselects some radio 
      buttons. Like checkboxes, radio buttons are never selected to begin with, 
      so you should use /did -c to select one radio button in each group in the 
      'init' event. We check radio buttons 1 and 3 here. 
      The 'sclick' events all store values in our variables according to the 
      radio button selected. The radio buttons automatically 'deselect' the 
      other buttons in the group- we simply use 'sclick' events to keep track of 
      which option is selected in each group. 
      Finally, in the 'sclick' event for the button (id 100) we display in 
      status which options were selected, and unset our variables. 
      Note that we do NOT have to track these with variables if we do not want- 
      $did().state works on radio buttons just like it does on checkboxes. 
      However, it still returns only 0 or 1 for each button, so you have to 
      check EACH button in a group to find the one that is selected. 

            EDITBOXES 


      This dialog shows how to make various types of editboxes, for entering in 
      text. 
      dialog editbox { 
        title "Editbox Samples" 
        size -1 -1 500 400 
        
        text "Basic editbox", 1, 5 5 240 20 
        edit "", 2, 5 25 100 22 
        
        text "Multi line with enter", 3, 250 5 240 20 
        edit "", 4, 250 25 200 70, multi return 
        
        text "Password field", 5, 5 100 240 20 
        edit "", 6, 5 120 200 22, pass result 
        
        text "Horizontal auto-scroll", 7, 250 100 240 20 
        edit "", 8, 250 120 50 22, autohs 
        
        text "Large box with scrollbars", 9, 5 200 240 20 
        edit "", 10, 5 220 200 80, multi return hsbar vsbar 
        
        text "Can't edit it!", 11, 250 200 240 20 
        edit "Hahahahaha", 12, 250 220 200 22, read 
        
        button "OK", 100, 200 340 100 25, ok 
      } 
      alias dlg5 { echo -s password: $dialog(editbox,editbox,0) } 

      Open this dialog, and notice how each editbox works. Editboxes are 
      controls of the 'edit' type. The width and height determines how large the 
      box itself is. Other than that, the only new things here are the various 
      styles. However, these are very important- editboxes have many important 
      styles. 
      The basic editbox only contains one line and you cannot type past the 
      boundaries. 
      Add the 'multi' capability, and you can type multiple lines if you type 
      past the right edge. (word wrap) The 'return' capability adds the ability 
      to press Enter for a new line. 
      The 'autohs' capability sets an editbox so that it automatically scrolls 
      horizontally. This allows entering more data than will show in the 
      editbox. You can do this for vertical scrolling using 'autovs'. 
      The 'hsbar' and 'vsbar' styles add horizontal and vertical scrollbars, 
      respectively. This allows manual scrolling. 
      The 'read' style makes a box read only, and the 'pass' style makes an 
      editbox show '***' for password entry. (the 'password' is not encrypted in 
      any way) 
      Play with the styles (especially the scrolling and multiline styles) to 
      get a feel for which ones are needed in which circumstances. 

            OPENING MULTIPLE DIALOGS 


      The last important point that needs to be made is having one dialog open 
      another dialog. (or a $? query box, a $dir directory listing, etc.) mIRC 
      CANNOT call popup boxes from within an event. This includes $dialog, $?, 
      $dir, and applies to dialog events. 
      mIRC 5.51 could not call /dialog from an event either, but mIRC 5.6 can 
      now use /dialog directly in an event. However, you still cannot use 
      $dialog, $dir, etc. from within an event, so this technique is still very 
      important. 
      There is a simple workaround, and that is the use of /timer. 
      Here's a simple example. 
      dialog first { 
        title "First" 
        size 50 50 110 100 
        
        button "Click me!", 100, 5 5 100 25, default 
        button "Close", 200, 5 50 100 25, ok 
      } 
      dialog second { 
        title "Second" 
        size 150 150 110 80 
        button "Close", 200, 5 50 100 25, cancel default 
      } 
      on *:DIALOG:first:sclick:100:.timer 1 0 dlg6b 

      alias dlg6 { /dialog -am first first } 
      alias dlg6b { %temp = $dialog(second,second,-4) } 

      /dlg6 will open one dialog, and /dlg6b will open the second. Also, when 
      you have the first open, clicking 'Click me!' will open the second. 
      Notice that the 'sclick' event does NOT just call /dlg6b. Instead, it uses 
      a timer. The timer runs once (1) and executes immediately (0) so the user 
      sees no delay. 
      Whenever you use this workaround, you should always put the desired code 
      in a NEW alias. Don't try to do the following-\ 
      .timer 1 0 set %var $dir="select file:" c:\ 

      Instead, do- 
      .timer 1 0 doit 
      alias doit { 
        set %var $dir="select file:" c:\ 
      } 

      This is because timers immediately evaluate their contents, then 
      reevaluate them again when they fire. This is good sometimes, and can be 
      worked around, but the easiest way to prevent problems is to just use 
      seperate aliases. 
      If you ever have problems making dialogs open more dialogs or file 
      selection boxes, etc. this is the trick you need. 

            MORE INFO 


      For more help, you can look up /dialog info in the mIRC help file. Some 
      important things we didn't cover- 
        Listboxes/comboboxes 
        Icons/bitmaps 
        Boxes 
        Various styles (disable, hide, etc.) 
        Some dialog events 
        Most uses of /did 
        Extended uses of /dialog 
        Extended uses of $dialog 
      As you can see, dialogs are a very large topic. Future tutorials at paiRC 
      may cover specific areas in depth, but this tutorial and the samples file 
      can hopefully get you started. 
      The following file contains further examples to work from- some are 
      similar to the ones in this article, some are unique to the file. 
            Download dialog-samples.mrc (Dialog examples )

      If you have any suggestions or additions for this article or wish to 
      submit an article or idea, please contact webgoddess@pairc.com


      Copyright and usage restrictions

